home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / index.arc / READ.ME < prev   
Encoding:
Text File  |  1987-08-31  |  13.5 KB  |  431 lines
  1.         This collection of QuickBASIC sub-programs is supplied 'as is'. I 
  2.         guarantee  nothing!  I have tested these routines thoroughly  and 
  3.         they  work  - to  the best of my knowledge.  If you find  a  bug, 
  4.         please let me know and I'll correct it as soon as possible.
  5.  
  6.  
  7.                                    Roy Barrow
  8.                                 222 Church Street
  9.                                   Philadelphia
  10.                                     PA 19106
  11.  
  12.              BASIC Programmers Bulletin Board System (215) 627-3910
  13.  
  14.                               or you can call me on
  15.                                  (215) 922 2557
  16.  
  17.  
  18.  
  19.                              AEBITCLS - SUB PROGRAM
  20.  
  21.         Close an index file.  To close an index file,  the number of that 
  22.         index is passed to the routine.  The index file proper is closed, 
  23.         the header file is opened and the index data in memory is written 
  24.         to the header / control file.
  25.  
  26.         CALLING SEQUENCE & PARAMETER LIST
  27.  
  28.              CALL bit.close(fl%)
  29.  
  30.         WHERE
  31.  
  32.              fl%  is the file number of the index.
  33.  
  34.  
  35.  
  36.                              AEBITCRE - SUB PROGRAM 
  37.  
  38.         This routine asks the questions needed to created an index  file. 
  39.         This  routine is supplied for interest only and is superseded  by 
  40.         AEBITCRQ. This will not be supported in future releases.
  41.  
  42.         Questions:
  43.  
  44.              name of header file 
  45.              length of key 
  46.  
  47.         CALLING SEQUENCE & PARAMETER LIST
  48.  
  49.              call bit.creat 
  50.  
  51.  
  52.  
  53.  
  54.                              AEBITCRQ - SUB PROGRAM
  55.  
  56.         This routine is parameter driven, and serves only to create a NEW 
  57.         index file. Existing files should be OPEN'ed with AEBITOPE.
  58.  
  59.         Each index has two files,  one is a header file, and the other is 
  60.         the  index  proper.  (.HDR and .IDX).  The header  file  contains 
  61.         information  regarding  the structure of  the  index  proper.  On 
  62.         opening  the  index,   the  header  file  is  read  into  control 
  63.         variables,  the  header  is  closed,  and then the  actual  index 
  64.         opened. 
  65.  
  66.         The reverse is accomplished when the index is closed:  The  index 
  67.         closed, the header opened, and the new updated info is written to 
  68.         the header file.
  69.  
  70.  
  71.         CALLING SEQUENCE & PARAMETER LIST
  72.  
  73.              call bit.creatq(fl%,flnm$,key.length%)
  74.  
  75.         WHERE
  76.                 
  77.              fl% is the index file number
  78.              flnm$ is the eight character index name (mo extension)
  79.              key.length% is an integer between 4 & 255
  80.  
  81.  
  82.                              AEBITFIN - SUB PROGRAM
  83.  
  84.         This  routine will attempt to find a key matching exactly that of 
  85.         the item passed to it. Failing that, it will return the 'closest' 
  86.         match.  If  a  close match is returned,  this is indicated  by  a 
  87.         negative relative record number for the key. 
  88.  
  89.         For  programs where 'close' match selection is important,  it  is 
  90.         suggested that you use the Key.Select.Box routine in which a list 
  91.         of keys would be displayed and a scroll selection  possible.  (It 
  92.         is  quite  possible  for  a user program to use  this  method  to 
  93.         traverse the whole index).
  94.  
  95.         I  am including the comments that lead into this routine  in  the 
  96.         documenting file.  Please note: this will be done throughout this 
  97.         document  in  an  effort to cut writing time down,  and  to  make 
  98.         things clearer ?
  99.  
  100.         Find  a key in the index.  If the find was a  success,  then  two 
  101.         values  are actually returned.  Success% holds the pointer to the 
  102.         physical  position on the index,  while mrec% returns the  master 
  103.         record number.  The find actually returns a match directly on the 
  104.         key being looked for. If there was no direct match, then ky$ will 
  105.         return  the  match before the return,  mrec% will  have  a  minus 
  106.         record  number value,  and success% will return the pointer  into 
  107.         the index - for the bit.next and bit.prev routines to use.
  108.  
  109.  
  110.  
  111.         CALLING SEQUENCE & PARAMETER LIST
  112.  
  113.              call bit.find(fl%,ky$,mrec%,success%)
  114.  
  115.         WHERE
  116.  
  117.              fl% is the index file number
  118.              ky$ is the key to search the index file for
  119.              mrec% is the record number ind the indexed file
  120.              success% is described above
  121.  
  122.  
  123.  
  124.                              AEBITINS - SUB PROGRAM
  125.  
  126.         This will allow a key to be inserted into an index.  This routine 
  127.         does not check for duplicates. If duplication checking is needed, 
  128.         then  it's important that you use the FIND routine to see if it's 
  129.         there.  It's  up  to an application program to check if  the  key 
  130.         exists.  I've done it this way so that you can decide to make  an 
  131.         index accept duplicate keys or not.
  132.  
  133.         CALLING SEQUENCE & PARAMETER LIST
  134.  
  135.              call bit.ins(fl%,ky$,mrec%,success%) 
  136.  
  137.         WHERE
  138.  
  139.              fl% is the index file number
  140.              ky$ is the key to insert into the index file
  141.              mrec% is the master record number passed to bit.ins
  142.              success% is 0 on a failure, 1 if ok
  143.              
  144.  
  145.  
  146.                              AEBITKIL - SUB PROGRAM
  147.  
  148.         This  delete routine is the most complex of those in the indexing 
  149.         package.  If it is changed, it should be done so with great care. 
  150.         I  spent  many  long  hours  ensuring  that  it  handled   *most* 
  151.         eventualities. Please be careful!
  152.  
  153.         This routine is usually the most time consuming. This is the only 
  154.         routine  that actually 'moves' records around in the  file.  This 
  155.         comes  about when you are deleting the master-parent key  (record 
  156.         1)  and  one of the children needs' to be  moved.  Also,  if  you 
  157.         delete  a  key  in the index and it happens to be  the  only  one 
  158.         there,  then  the  routine will truncate the file (making  future 
  159.         accesses somewhat faster).
  160.  
  161.         A  call to FIND should ALWAYS precede DELETE.  This will  set  up 
  162.         pointers in memory for DELETE to use. 
  163.  
  164.         On  return  from  delete,  success% will be zero if  the  routine 
  165.         failed, otherwise success% will equal 1.
  166.  
  167.  
  168.  
  169.         CALLING SEQUENCE & PARAMETER LIST
  170.  
  171.              call bit.kill(fl%,ky$,mrec%,success%) 
  172.  
  173.         WHERE
  174.  
  175.              fl% is the index file number
  176.              ky$ is the key to delete into the index file
  177.              mrec% is the master record number passed (from bit.find)
  178.              success% is 0 on a failure, 1 if ok
  179.  
  180.  
  181.  
  182.                              AEBITLFT - SUB PROGRAM
  183.  
  184.  
  185.         Bit.left  moves  the  index pointer so  that  it  references  the 
  186.         smallest  key in the tree.  This function is to be used to get  a 
  187.         listing  of  the tree in sequence.  The 'bit.right' routine  will 
  188.         position  the  pointer at the other end of the tree  for  reverse 
  189.         listings.
  190.  
  191.         CALLING SEQUENCE & PARAMETER LIST
  192.  
  193.              call bit.left(fl%,ky$,mrec%,success%) 
  194.  
  195.         WHERE
  196.  
  197.              fl% is the index file number
  198.              ky$ is the key to delete into the index file
  199.              mrec% is the master record number passed (from bit.find)
  200.              success% is 0 on a failure, 1 if ok
  201.  
  202.  
  203.                              AEBITNEX - SUB PROGRAMS
  204.  
  205.         This  routine  will  return the next key in the  index  from  the 
  206.         current one.  If there are no current values for the key,  then a 
  207.         negative value will be returned, else a positive value indicating 
  208.         the  records - master and index - will be returned (or a zero  if 
  209.         no next key).
  210.  
  211.         CALLING SEQUENCE & PARAMETER LIST
  212.  
  213.              call bit.next(fl%,ky$,mrec%,success%)
  214.  
  215.         WHERE
  216.  
  217.              fl% is the index file number
  218.              ky$ is the key to delete into the index file
  219.              mrec% is the master record number passed (from bit.find)
  220.              success% is 0 on a failure, 1 if ok
  221.  
  222.  
  223.  
  224.  
  225.  
  226.                              AEBITOPE - SUB PROGRAM
  227.  
  228.         This  is the ONLY way an index file can be opened.  This  routine 
  229.         sets  up  parameters  in memory for subsequent  access  by  other 
  230.         routines.
  231.  
  232.         CALLING SEQUENCE & PARAMETER LIST
  233.  
  234.              call bit.open(fl%,hn$) 
  235.  
  236.         WHERE
  237.  
  238.              fl% is the index file number
  239.              hn$ is the name of the index (8 ch, excluding extension)
  240.  
  241.  
  242.                              AEBITPRV - SUB PROGRAM
  243.  
  244.         This  is  much  the same as the 'next' function  except  that  it 
  245.         returns the key previous to the currently selected one.  This can 
  246.         be usefull for printing a report in reverse sequence.
  247.  
  248.         CALLING SEQUENCE & PARAMETER LIST
  249.  
  250.              call bit.prev(fl%,ky$,mrec%,success%)
  251.  
  252.         WHERE
  253.  
  254.              fl% is the index file number
  255.              ky$ is the key to delete into the index file
  256.              mrec% is the master record number passed (from bit.find)
  257.              success% is 0 on a failure, 1 if ok
  258.  
  259.  
  260.  
  261.                              AEBITRGT - SUB PROGRAM
  262.  
  263.         Bit.right  moves  the  index pointer so that  it  references  the 
  264.         largest   key in the tree.  this function is to be used to get  a 
  265.         listing  of  the tree in sequence.  The 'bit.left'  routine  will 
  266.         position  the pointer  at the other end of the tree  for  forward 
  267.         listings.
  268.  
  269.         CALLING SEQUENCE & PARAMETER LIST
  270.  
  271.              call bit.right(fl%,ky$,mrec%,success%) static
  272.  
  273.         WHERE
  274.  
  275.              fl% is the index file number
  276.              ky$ is the key to delete into the index file
  277.              mrec% is the master record number passed (from bit.find)
  278.              success% is 0 on a failure, 1 if ok
  279.  
  280.  
  281.  
  282.  
  283.  
  284.                              AECOMMON - SUB PROGRAM
  285.  
  286.         These  COMMON definitions should be placed right at the start  of 
  287.         your programs, with the INCLUDE meta command. Refer to page -188- 
  288.         of the Microsoft QuickBASIC 2.00 Compiler Guide.
  289.  
  290.  
  291.  
  292.  
  293.                              AEGETFLS - SUB PROGRAM
  294.  
  295.         This works in conjunction with the other file accessing routines, 
  296.         and  returns information regarding the OPEN / CLOSED status of  a 
  297.         file.
  298.  
  299.  
  300.  
  301.  
  302.         CALLING SEQUENCE & PARAMETER LIST
  303.                 
  304.              call Get.File.Status(fl%,rlen%,st%) 
  305.  
  306.         WHERE
  307.  
  308.              fl% is the file number
  309.              rlen% is the record length of this file
  310.              st% is the status returned (1=OPEN , 2=CLOSED)
  311.  
  312.  
  313.  
  314.                              AEGETREC - SUB PROGRAM
  315.  
  316.         Allocates  and returns the next available record in a file.  When 
  317.         records are deleted, they are pushed on to the top of this stack.
  318.  
  319.         CALLING SEQUENCE & PARAMETER LIST
  320.  
  321.              call Get.Avail.Record (fl%,rlen%,rec%)
  322.  
  323.         WHERE
  324.  
  325.              fl% is the file number
  326.              rlen% is the record length
  327.              rec% is the record number returned
  328.  
  329.  
  330.  
  331.  
  332.                              AEINITFL - SUB PROGRAM
  333.  
  334.         This initializes a new file's header record for subsequent access 
  335.         with the other record allocation routines.
  336.  
  337.         CALLING SEQUENCE & PARAMETER LIST
  338.  
  339.              call Init.New.File(fl%,rlen%)
  340.  
  341.         WHERE
  342.  
  343.              fl% is the file number
  344.              rlen% is the record length
  345.  
  346.  
  347.  
  348.                              AEMRKCLS - SUB PROGRAM
  349.  
  350.         Mark  a  file as closed (works with the record number  allocation 
  351.         routines).
  352.  
  353.         CALLING SEQUENCE & PARAMETER LIST
  354.  
  355.              call Mark.File.Closed(fl%,rlen%) 
  356.  
  357.         WHERE
  358.  
  359.              fl% is the file number
  360.              rlen% is the record length
  361.  
  362.  
  363.  
  364.                              AEMRKOPE - SUB PROGRAM
  365.  
  366.         Mark  a  file as open (works with the  record  number  allocation 
  367.         routines).
  368.  
  369.         CALLING SEQUENCE & PARAMETER LIST
  370.  
  371.              call Mark.File.Open(fl%,rlen%) 
  372.  
  373.         WHERE
  374.  
  375.              fl% is the file number
  376.              rlen% is the record length
  377.  
  378.  
  379.  
  380.                              AERELREC - SUB PROGRAM
  381.  
  382.         Release an allocated record (delete) using the record  allocation 
  383.         system.
  384.  
  385.         CALLING SEQUENCE & PARAMETER LIST
  386.  
  387.              call Release.Avail.Record(fl%,rlen%,rec%) 
  388.  
  389.         WHERE
  390.  
  391.              fl% is the file number
  392.              rlen% is the record length
  393.              rec% is the record to release
  394.  
  395.  
  396.  
  397.  
  398.                              AESHARED - SUB PROGRAM
  399.  
  400.         To be included in all externally compile sub-programs
  401.  
  402.  
  403.  
  404.                                IDXTEST4 - PROGRAM
  405.  
  406.         This program is used for testing the indexing routines.  It could 
  407.         also serve as a demonstration of the use of the routines. It is a 
  408.         hastily put together piece of software so is *very* inelegant. To 
  409.         use  the  program,  you need to CREATE a file and then  OPEN  the 
  410.         file. You can then use the other accessing routines.
  411.  
  412.  
  413.                                  NAMES - PROGRAM
  414.  
  415.         Names  is a demonstration program of some of the routines in  the 
  416.         program  library.  It  served initially as demo of  the  indexing 
  417.         routines,  but could be an indication of how the menu and  dialog 
  418.         routines work.
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.         Version Number 1.1, 15 February, 1987                 Page 19
  426.  
  427.  
  428.  
  429.  
  430.  
  431.